---
title: CSS & 스타일링
description: 맞춤형 CSS로 Starlight 사이트의 스타일을 지정하거나 Tailwind CSS와 통합하는 방법을 알아보세요.
---

import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';

사용자 정의 CSS 파일을 사용하여 Starlight 사이트의 스타일을 지정하거나 Starlight Tailwind 플러그인을 사용할 수 있습니다.

## 사용자 정의 CSS 스타일

Starlight의 기본 스타일을 수정하거나 확장하기 위한 CSS 파일을 제공하여 사이트에 적용된 스타일을 원하는대로 변경할 수 있습니다.

<Steps>

1. `src/` 디렉터리에 CSS 파일을 추가합니다. 예를 들어, 아래 코드를 통해 페이지 제목을 더 넓게 만들고, 더 큰 텍스트를 사용할 수 있습니다.

   ```css
   /* src/styles/custom.css */
   :root {
   	--sl-content-width: 50rem;
   	--sl-text-5xl: 3.5rem;
   }
   ```

2. `astro.config.mjs` 파일에 있는 Starlight의 `customCss` 배열에 CSS 파일 경로를 추가하세요.

   ```diff lang="js"
   // astro.config.mjs
   import { defineConfig } from 'astro/config';
   import starlight from '@astrojs/starlight';

   export default defineConfig({
   	integrations: [
   		starlight({
   			title: '사용자 정의 CSS를 사용한 문서',
   			customCss: [
   +				// 사용자 정의 CSS 파일의 상대 경로
   +				'./src/styles/custom.css',
   			],
   		}),
   	],
   });
   ```

</Steps>

사이트를 스타일링하기 위해 Starlight에서 사용되는 모든 CSS 속성을 [`props.css` 파일](https://github.com/withastro/starlight/blob/main/packages/starlight/style/props.css)에서 확인할 수 있습니다.

## Tailwind CSS

Astro 프로젝트의 Tailwind CSS 지원은 [Astro Tailwind 통합](https://docs.astro.build/ko/guides/integrations-guide/tailwind/)을 통해 제공됩니다.
Starlight는 Starlight 스타일과 호환되도록 Tailwind를 구성하는 데 도움이 되는 보완 Tailwind 플러그인을 제공합니다.

Starlight Tailwind 플러그인은 다음 구성을 적용합니다.

- Starlight의 다크 모드와 작동하도록 Tailwind의 `dark:` 변형을 구성합니다.
- Starlight UI에서 Tailwind [테마 색상 및 글꼴](#tailwind로-starlight-스타일링하기)을 사용합니다.
- Tailwind의 [Preflight](https://tailwindcss.com/docs/preflight) 초기화 스타일을 비활성화하는 동시에 Tailwind의 테두리 유틸리티 클래스에 필요한 Preflight의 필수 부분을 선택적으로 복원합니다.

### Tailwind가 포함된 새 프로젝트 만들기

`create astro`를 사용하여 Tailwind CSS가 사전 구성된 새 Starlight 프로젝트를 시작하세요.

<Tabs syncKey="pkg">
<TabItem label="npm">

```sh
npm create astro@latest -- --template starlight/tailwind
```

</TabItem>
<TabItem label="pnpm">

```sh
pnpm create astro --template starlight/tailwind
```

</TabItem>
<TabItem label="Yarn">

```sh
yarn create astro --template starlight/tailwind
```

</TabItem>
</Tabs>

### 기존 프로젝트에 Tailwind 추가

이미 Starlight 사이트가 존재할때, Tailwind CSS를 추가하려면 다음 단계를 따르세요.

<Steps>

1.  Astro의 Tailwind 통합 추가

    <Tabs syncKey="pkg">

    <TabItem label="npm">

    ```sh
    npx astro add tailwind
    ```

    </TabItem>

    <TabItem label="pnpm">

    ```sh
    pnpm astro add tailwind
    ```

    </TabItem>

    <TabItem label="Yarn">

    ```sh
    yarn astro add tailwind
    ```

    </TabItem>

    </Tabs>

2.  Starlight Tailwind 플러그인을 설치하세요.

    <Tabs syncKey="pkg">

    <TabItem label="npm">

    ```sh
    npm install @astrojs/starlight-tailwind
    ```

    </TabItem>

    <TabItem label="pnpm">

    ```sh
    pnpm add @astrojs/starlight-tailwind
    ```

    </TabItem>

    <TabItem label="Yarn">

    ```sh
    yarn add @astrojs/starlight-tailwind
    ```

    </TabItem>

    </Tabs>

3.  `src/tailwind.css` 파일과 같은 Tailwind의 기본 스타일에 대한 CSS 파일을 만드세요.

    ```css
    /* src/tailwind.css */
    @tailwind base;
    @tailwind components;
    @tailwind utilities;
    ```

4.  Tailwind 기반 스타일을 사용하고 기본 스타일을 비활성화하려면 Astro 구성 파일을 업데이트하세요.

    ```js {11-12,16-17}
    // astro.config.mjs
    import { defineConfig } from 'astro/config';
    import starlight from '@astrojs/starlight';
    import tailwind from '@astrojs/tailwind';

    export default defineConfig({
    	integrations: [
    		starlight({
    			title: 'Tailwind를 사용한 문서',
    			customCss: [
    				// Tailwind 기반 스타일 경로
    				'./src/tailwind.css',
    			],
    		}),
    		tailwind({
    			// 기본 스타일을 비활성화합니다.
    			applyBaseStyles: false,
    		}),
    	],
    });
    ```

5.  `tailwind.config.mjs` 파일에 Starlight Tailwind 플러그인을 추가하세요.

    ```js ins={2,7}
    // tailwind.config.mjs
    import starlightPlugin from '@astrojs/starlight-tailwind';

    /** @type {import('tailwindcss').Config} */
    export default {
    	content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'],
    	plugins: [starlightPlugin()],
    };
    ```

</Steps>

### Tailwind로 Starlight 스타일링하기

Starlight는 UI에서 [Tailwind 테마 구성](https://tailwindcss.com/docs/theme) 값을 사용합니다.

설정된 경우 다음 옵션이 Starlight의 기본 스타일을 재정의합니다.

- `colors.accent` — 링크 및 현재 항목 강조에 사용됩니다.
- `colors.gray` — 배경색과 테두리에 사용됩니다.
- `fontFamily.sans` — UI 및 콘텐츠 텍스트에 사용됩니다.
- `fontFamily.mono` — 코드 예제에 사용됩니다.

```js {12,14,18,20}
// tailwind.config.mjs
import starlightPlugin from '@astrojs/starlight-tailwind';
import colors from 'tailwindcss/colors';

/** @type {import('tailwindcss').Config} */
export default {
	content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'],
	theme: {
		extend: {
			colors: {
				// 선호하는 강조 색상입니다. Indigo는 Starlight의 기본값에 가장 가깝습니다.
				accent: colors.indigo,
				// 선호하는 회색조입니다. Zinc는 Starlight의 기본값에 가장 가깝습니다.
				gray: colors.zinc,
			},
			fontFamily: {
				// 선호하는 텍스트 글꼴입니다. Starlight는 기본적으로 시스템 글꼴 스택을 사용합니다.
				sans: ['"Atkinson Hyperlegible"'],
				// 선호하는 코드 글꼴입니다. Starlight는 기본적으로 시스템 고정 폭 글꼴을 사용합니다.
				mono: ['"IBM Plex Mono"'],
			},
		},
	},
	plugins: [starlightPlugin()],
};
```

## 테마

기본 사용자 정의 속성을 변경하여 Starlight의 색상 테마를 제어할 수 있습니다.
이러한 변수는 텍스트 및 배경색에 사용되는 다양한 회색 음영과 링크에 사용되는 강조 색상 및 탐색에서 현재 항목을 강조 표시하는 UI 전체에서 사용됩니다.

### 색상 테마 편집기

아래 슬라이더를 사용하여 Starlight의 강조 및 회색 색상 팔레트를 수정하세요. 어둡고 밝은 미리보기 영역에는 결과 색상이 표시되며 전체 페이지도 업데이트되어 변경 사항을 미리 확인할 수 있습니다.

대비 수준 옵션을 사용하여 웹 콘텐츠 접근성 가이드라인 [색상 대비 표준](https://developer.mozilla.org/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable/Color_contrast) 중 어느 것을 충족할지 지정합니다.

변경 사항이 만족스러우면 아래 CSS 또는 Tailwind 코드를 복사하여 프로젝트에 사용하세요.

import ThemeDesigner from '~/components/theme-designer.astro';

<ThemeDesigner
	labels={{
		presets: {
			label: '프리셋',
			ocean: '오션',
			forest: '숲',
			oxide: '옥사이드',
			nebula: '성운',
			default: '기본값',
			random: '무작위',
		},
		contrast: {
			label: '대비 수준',
		},
		editor: {
			accentColor: '강조',
			grayColor: '회색조',
			hue: '색상',
			chroma: '채도',
			pickColor: '색상 선택',
		},
		preview: {
			darkMode: '어두운 테마',
			lightMode: '밝은 테마',
			bodyText: '본문 텍스트는 배경과 대비가 높은 회색 음영으로 표시됩니다.',
			linkText: '링크에 색상이 지정됩니다.',
			dimText: '콘텐츠 목차와 같은 일부 텍스트는 대비가 낮습니다.',
			inlineCode: '인라인 코드에는 뚜렷한 배경이 있습니다.',
		},
	}}
>
	<Fragment slot="css-docs">
		[사용자 정의 CSS파일](#사용자-정의-css-스타일)에 아래 코드를 추가하여 현재 테마를 프로젝트에 적용하세요.
	</Fragment>
	<Fragment slot="tailwind-docs">
		아래 [Tailwind 구성 파일](#tailwind로-starlight-스타일링하기)의 예시는 `theme.extend.colors`에서 사용할 `accent` 및 `gray` 색상 팔레트를 포함합니다.
    </Fragment>

</ThemeDesigner>
